home *** CD-ROM | disk | FTP | other *** search
/ Nebula 1 / Nebula One.iso / Internet / WWW / Perl_WWW_Utilities / page-stats / README < prev   
Encoding:
Text File  |  1995-07-25  |  6.5 KB  |  156 lines
  1.  
  2. NAME
  3.        page-stats.pl - Check WWW page accesses (v1.3)
  4.  
  5. SYNOPSIS
  6.        page-stats.pl -h
  7.        page-stats.pl [ -b ] [ -i identfile ] [ -l logfile ]
  8.  
  9. DESCRIPTION
  10.        page-stats.pl will examine the acceslog of a http daemon and search
  11.        it for occurrences of certain references. These references are then
  12.        counted  and  put into a HTML file that is ready to be displayed to
  13.        the  outside  world  as  a "Page Statistics" page. Each page can be
  14.        selected from the statistics page.
  15.  
  16.        The  identfile  contains  the  references that should be counted. A
  17.        line in this file should be in the following format:
  18.  
  19.               URL@title@reference[@reference...]
  20.  
  21.        which could look like this:
  22.  
  23.               ~gnu/index.html@Gnu's pages@/gnu.html@~gnu*
  24.  
  25.        Comments  are  allowed, and should be preceded by a "#". Everything
  26.        following that character will be ignored. Each line should at least
  27.        contain the following:
  28.  
  29.        URL    The  URL  of  the  page, as it should be referenced from the
  30.               "Page Statistics" page.
  31.  
  32.        title  The  title of the page, as you want visitors to see it. Note
  33.               that  leading  spaces  are significant, so it is possible to
  34.               make  use  of indentation for different levels of documents.
  35.  
  36.        reference
  37.               A reference of how the page might be accessed. For instance,
  38.               if  a  directory  contains  a  file  index.html,  it  can be
  39.               accessed  by  leaving out the "index.html" part, or even the
  40.               "/"  before  it.  If  this  is  the case, put all references
  41.               behind each other, separated by "@". You may use a wildcard
  42.               "*"  at  the  end  of a string to match only the begin of an
  43.               URL.
  44.  
  45.        The  order  of  the  lines in the identfile matters. Only the first
  46.        match  will be taken into account. Be careful when using wildcards,
  47.        as  they  might filter out hits for lines below. Take a look at the
  48.        (faulty) example below:
  49.  
  50.               # Wrong; second line will never be reached!
  51.               ~gnu/index.html@Gnu's pages@~gnu*
  52.               ~gnu/info/index.html@Gnu's info files@~gnu/info*
  53.  
  54.        The  first  line will filter out all URLs ending in ".html", which
  55.        automatically  means  that  URLs that would match /info/*.html are
  56.        matched  as  well.  Place the second line above the first to solve
  57.        the problem:
  58.  
  59.               # Right!
  60.               ~gnu/info/index.html@Gnu's info files@~gnu/info*
  61.               ~gnu/index.html@Gnu's pages@~gnu*
  62.  
  63.        Currently  page-stats.pl  will  skip  lines  in the access_log that
  64.        contain  references to ".gif", ".jpg" or ".jpeg" files, even if you
  65.        specify  matching  URLs.  If  you  need  the  program to be able to
  66.        handle  references  to  those  pictures,  you should outcomment the
  67.        lines as indicated in the code.
  68.  
  69.        Note  that  once  the  first matching reference is found, the quest
  70.        for  matches  is ended. Only the first page will be recognized as a
  71.        matching reference and its counter will be increased.
  72.  
  73.        The  HTML  "Page Statistics"  file is created from two files. These
  74.        are the ident file with references to check, and a source file that
  75.        contains  the  basic  HTML  page as desired. The name of the source
  76.        file  is  determined  by replacing the mandatory ".ident" ending of
  77.        the  ident file by ".source". The HTML file that is created will be
  78.        named in the same way, ending in ".html".
  79.  
  80.        It  is  possible to use certain variables in the source file. These
  81.        variables  will be replaced by page-stats.pl as it rummages through
  82.        the file.
  83.  
  84.        $date  The  current  date  and  time  will  be  inserted  for  this
  85.               variable.
  86.  
  87.        $firstrequest
  88.               The  date  and  time  of  the  first  request  logged in the
  89.               access_log will be inserted for this variable.
  90.  
  91.        $lastrequest
  92.               This  variable is replaced by the last request logged in the
  93.               access_log.
  94.  
  95.        $list  This  will  be  replaced  by the complete list of references
  96.               and their number of hits.
  97.  
  98.        $topN  This  will insert a sorted list of the N most visited pages,
  99.               where  N  can  be  any  number .  Of course setting a number
  100.               greater  than  the number of references is silly. There must
  101.               be no space between "$top" and the number.
  102.  
  103. OPTIONS
  104.        -b     Benchmark;  print  used  user  and  system times when ready.
  105.  
  106.        -h     Displays this manual page.
  107.  
  108.        -i identfile
  109.               Specify  the  file  that determines which references to look
  110.               for  in  the  logfile.  This defaults to 'page-stats.ident'.
  111.  
  112.        -l logfile
  113.               Specify  the  access_log  of  the  http  daemon. The default
  114.               location is '/usr/local/httpd/logs/access_log'.
  115.  
  116. FILES
  117.        access_log           (generated by httpd)
  118.        <identname>.ident
  119.        <identname>.source   (optional)
  120.        <identname>.html     (generated by page-stats.pl)
  121.  
  122. SEE ALSO
  123.        httpd(1).
  124.        http://www.sci.kun.nl/thalia/guide/#page-stats
  125.               For the latest version.
  126.        http://www.sci.kun.nl/thalia/page-stats/
  127.               For a working example.
  128.  
  129. CHANGES
  130.        03-01-1995:  (v1.0) First draft of the program.
  131.        03-17-1995:  (v1.1) Added 'total number of requests' at the bottom
  132.                     of the page.
  133.        05-26-1995:  (v1.2) Added  '$topN'  and  '$list'; juggled with the
  134.                     code.  Improved  performance  by  skipping  images in
  135.                     access_log.  Allowed comments in the ident file. Also
  136.                     moved the external README into the code.
  137.        07-17-1995:  (v1.3) You  can  now  use wildcards to define URLs to
  138.                     recognize.  Using arrays to administrate URLs instead
  139.                     of strings.
  140.        
  141. BUGS
  142.        If  the  accesslog is big, and there are many references to check,
  143.        this  program  can  take  very long to complete. It is recommended
  144.        that  both  the size of the accesslog and the number of references
  145.        are kept to acceptable levels.
  146.  
  147.        The  program  might not work because the path to Perl in the first
  148.        line  of  page-stats.pl  is  wrong.  See if the path is correct by
  149.        doing  'which perl' at your Unix prompt. If it is not correct, you
  150.        will have to edit the first line.
  151.  
  152. AUTHOR
  153.        Mark Koenen <markko@sci.kun.nl>,
  154.        changes by Patrick Atoon <patricka@cs.kun.nl>
  155.  
  156.